LOOT Metadata Syntax

Contents

1. Introduction
2. Metadata File Contents
3. Data Structures
   1. Tag Data Structure
   2. File Data Structure
   3. Message Data Structure
   4. Location Data Structure
   5. Dirty Info Data Structure
   6. Plugin Data Structure
4. Condition Strings
   1. Functions
   2. The Negator & Junctors
   3. Order Of Evaluation
5. Language Codes
6. Version History
7. License

Introduction

The metadata syntax is what LOOT's masterlists and userlists are written in. If you know YAML, good news: the syntax is essentially just YAML 1.2. If you don't know YAML, then its Wikipedia page is a good introduction. All you really need to know is:

• How lists and associative arrays (key-value maps) are written.
• That whitespace is important, and that only normal spaces (ie. no non-breaking spaces or tabs) count as such.
• That data entries that are siblings must be indented by the same amount, and child data nodes must be indented further than their parents (see the example later in this document if you don't understand).
• That YAML files must be written in a Unicode encoding.
• That each key in a key-value map must only appear once per map object.

An important point that is more specific to how LOOT uses YAML:

• Strings are case-sensitive, apart from file paths, regular expressions and checksums.

Some properties of file paths as used by LOOT:

• They are evaluated as paths relative to the game's Data folder.
• They cannot reference a path outside of the game's folder structure, ie. they cannot contain the substring ../../.
• Regular expression file paths must be written in the EMCAScript syntax.
• Only the filename of a regex file path may contain non-literal regex syntax, ie. if the filename part of the regex file path is removed, the remainder must be an exact folder path (though with the regex syntax special characters escaped). For example, given the regex file path Meshes\\Resources(1|2)\\(upperclass)?table.nif, LOOT will look for a file named table.nif or upperclasstable.nif in the Meshes\Resources(1|2) folder, rather than looking in the Meshes\Resources1 and Meshes\Resources2 folders.

In this document, where a value's type is given as X list, this is equivalent to a YAML sequence of values which are of the data type X. Where a value's type is given as X set, this is equivalent to a YAML sequence of unique values which are of the data type X. Uniqueness is determined using the equality criteria for that data type. All the non-standard data types that LOOT's metadata syntax uses have their equality criteria defined later in this document.

Metadata File Contents

The root of a metadata file is a key-value map. LOOT will recognise the following keys, none of which are required:

Other keys may also be present, but are not processed by LOOT. The message and plugin data structures are detailed in the next section.

An example metadata file:

bash_tags:
  - 'C.Climate'
  - 'Relev'
globals:
  - type: say
    content: 'You are using the latest version of LOOT.'
    condition: 'version("LOOT", "0.5.0.0", ==)'
plugins:
  - name: 'Armamentarium.esm'
    tag:
      - Relev
  - name: 'ArmamentariumFran.esm'
    tag:
      - Relev
  - name: 'Beautiful People 2ch-Ed.esm'
    tag:
      - Eyes
      - Graphics
      - Hair
      - R.Relations

Data Structures

LOOT expects metadata to be laid out using a certain set of data structures, described in this section.

Tag Data Structure

LOOT metadata files can contain suggestions for the addition or removal of Bash Tags, and this is the structure used for them. It has two forms: a key-value map and a scalar string.

Map Form

All values in the map are strings.

Scalar Form

tag

where tag is equivalent to the value of the name key in the map form.

Equality

Two tag data structures are equal if the lowercased values of their name keys are identical.

Examples

Relations

name: -Relations
condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm")'

File Data Structure

Not to be confused with the structure of the metadata file itself, this structure can be used to hold file paths. It has two forms: a key-value map and a scalar string.

Map Form

All values in the map are strings.

Scalar Form

filepath

where filepath is equivalent to the value of the name key in the map form.

Equality

Two file data structures are equal if the lowercased values of their name keys are identical.

Examples

'../obse_loader.exe'

name: '../obse_loader.exe'
condition: 'version("../obse_loader.exe", "0.0.18.0", >=)'
display: 'OBSE v18+'

Message Data Structure

Messages are given as key-value maps.

LOOT supports formatting of messages using GitHub Flavored Markdown. Support is provided by the Marked library (v0.3). Strings that get substituted into messages, such as file display names and dirty info utility strings, also support the same formatting options.

LOOT handles messages and languages as follows:

1. If a message's content value is a string, the message will use the string as its content if displayed.
2. If a message's content value is a list of localised content structures, then the first structure with a language that matches LOOT's current language will be used as the message's content if displayed. If there are no matches, then the first structure in English will be used.

Message Types

Localised Content Data Structure

The localised content data structure is a key-value map, with all values being strings:

Equality

The equality of two message data structures is determined by comparing the values of their content keys. As the values of the keys can be different types, a comparison value is selected for each message using the following logic:

• If a value's type is a localised content list, then the English content string in that list is selected as the comparison value.
• If a value's type is a string, then that string is selected as the comparison value.

The two message data structures are then equal if their lowercased comparison values are identical.

Examples
(translations by Google)

type: say
condition: 'file("foo.esp")'
content:
  - lang: en
    str: 'An example link: <http://www.example.com>'
  - lang: ru
    str: 'Это пример ссылки: <http://www.example.com>'

отмечать: Это пример ссылки: http://www.example.com

type: say
content: 'An alternative [example link](http://www.example.com), with no translations.'

отмечать: An alternative example link, with no translations.

type: say
content: 'A newer version of %1% [is available](%2%).
subs:
  - 'this plugin'
  - 'http://www.example.com'

Note: A newer version of this plugin is available.

Location Data Structure

This data structure is used to hold information on where a plugin is hosted online. It has two forms: a key-value map and a scalar string.

Map Form

All values in the map are strings.

Scalar Form

URL

where URL is equivalent to the value of the link key in the map form.

Equality

Two location data structures are equal if the lowercased values of their link keys are identical.

Examples

'http://skyrim.nexusmods.com/mods/19/'

link: 'https://steamcommunity.com/sharedfiles/filedetails/?id=419668499'
name: 'Unofficial Skyrim Patch on Steam Workshop'

Dirty Info Data Structure

This structure holds information on which versions of a plugin are dirty, and how many identical-to-master records, deleted records and deleted navmeshes (if applicable) it contains. Dirty info is given as a key-value map.

Equality

Two location data structures are equal if the values of their crc keys are identical.

Examples

crc: 0x3DF62ABC
util: '[TES5Edit](http://www.creationkit.com/TES5Edit_Cleaning_Guide_-_TES5Edit)'
itm: 4
udr: 160
nav: 0

Plugin Data Structure

This is the structure that brings all the others together, and forms the main component of a metadata file. It is a key-value map.

Equality

The equality of two plugin data structures is determined by comparing the values of their name keys.

• If neither or both values are regular expressions, then the plugin data structures are equal if the lowercased values are identical.
• If one value is a regular expression, then the plugin data structures are equal if the other value is an exact match for it.

Merging Behaviour

Examples

name: 'Oscuro''s_Oblivion_Overhaul.esm'
req:
  - 'Oblivion.esm'  # Don't do this, Oblivion.esm is a master of Oscuro's_Oblivion_Overhaul.esm, so LOOT already knows it's required.
  - name: 'example.esp'
    display: '[Example Mod](http://www.example.com)'
    condition: 'version("Oscuro''s_Oblivion_Overhaul.esm", "15.0", ==)'
tag:
  - Actors.Spells
  - Graphics
  - Invent
  - Relations
  - Scripts
  - Stats
  - name: -Relations
    condition: 'file("Mart''s Monster Mod for OOO.esm") or file("FCOM_Convergence.esm")'
msg:
  - type: say
    content: 'Do not clean. "Dirty" edits are intentional and required for the mod to function.'

Condition Strings

Condition strings can be used to ensure that data is only acted on by LOOT under certain circumstances. They are very similar to boolean conditional expressions in programming languages such as Python, though more limited. Their EBNF grammar is:

[ negator ], function, { junctor, [ negator ], function } ;

The [ negator ], function grammar is referred to as a condition, and two conditions joined by an operator, ie. condition, operator, condition is referred to as a compound condition.

LOOT caches the results of condition evaluations, so performance is not really an issue. A regular expression check will still take longer than a file check though, so use the former only when appropriate to do so.

Functions

There are several conditions that can be tested for using the functions detailed in the table below.

The different types of variable used in the above functions are described in more detail below.

The Negator & Junctors

The negator, or logical negation operator, inverts the value of the function that follows it. Its inclusion is optional, and its syntax is simply:

not

Below is a truth table for the negator.

There are two supported junctors, the logical conjunction (logical and operator) and the logical disjunction (logical or operator), that operate on the expressions to their left and right.

The following is a truth table for the junctors:

Order Of Evaluation

When a condition string is evaluated, its constituent parts are evaluated according to the standard precedence rules of operator logic, ie.

1. Function
2. Negator
3. Logical and
4. Logical or

Below is a table that lists some combinations of conditions, showing for each the order of evaluation by explicit bracketing. To make it easier to read, the negator function pair is shortened to C after the first example.

You can also explicitly enclose any condition in brackets to override the evaluation order, eg. C and ( C or C ) is evaluated as C and ( C or C ), in contrast to the unbracketed string above.

Language Codes

LOOT supports the following languages and language codes:

Version History

Each version of LOOT has a corresponding version of the metadata format, and its version history is given below.

0.8

• Removed support for the ver key in location data structures.
• Added support for the name key in location data structures.
• Added support for the many("regex") condition function.
• Changed detection of regular expression plugin entries. Previously, a plugin entry was treated as having a regular expression filename if the filename ended with \.esp or \.esp. Now, a plugin entry is treated as having a regular expression filename if the filename contains one or more of :\*?|.
• The plugin data structure definition in this document was fixed so that it correctly gives the values of the after, req, inc, tag, url and dirty keys as sets, not lists.
• This document now defines the equality criteria for all of the metadata syntax's non-standard data structures.
• The algorithm used for version comparison has been changed to give better results for a wider variety of version strings.

0.7

• Changed support for Markdown formatting in messages. Previously, only URL hyperlinking was supported, and only for file:, http: and https: URLs using the [label](url) or <url> syntaxes. Now, the Marked library (v0.3) is used to provide support for most of GitHub Flavored Markdown, minus the GitHub-specific features (like @mentions, issue/repo linking and emoji).
• Added support for message string substitution keys, i.e. sub, in message data structures.
• Added support for YAML merge keys, i.e. <<.

0.6

No changes.

0.5

Initial release.

License

This document is part of the LOOT documentation.
Copyright (C) 2012—2016 WrinklyNinja
See the file LOOT ReadMe.html for copying conditions.